---
title: useFixedPositioning
description: "The useFixedPositioning hooks is used to attach a temporary (fixed) element to another element within the page. In other words, this is a way to have an element with position: fixed as if it were position: absolute to a parent element that had position: relative."
docType: Demo
docGroup: Hooks
group: Resizing and Positioning
hooks: [useFixedPositioning]
---

# useFixedPositioning [$SOURCE](packages/core/src/positioning/useFixedPositioning.ts)

```ts disableTransform
function useFixedPositioning<
  FixedToElement extends HTMLElement,
  FixedElement extends HTMLElement,
>(
  options: FixedPositioningOptions<FixedToElement, FixedElement>
): FixedPositioningImplementation<FixedElement>;
```

The `useFixedPositioning` hooks is used to attach a temporary (fixed) element
to another element within the page. In other words, this is a way to have an
element with `position: fixed` as if it were `position: absolute` to a parent
element that had `position: relative`.

### Example Usage

The `useFixedPositioning` hook should generally be used with the
`useCSStransition` component as it provides `transitionOptions` for that hook
to be able to render correctly.

```demo source="./SimpleExample.tsx"

```

#### Advanced Configuration

The `useFixedPositioning` supports a lot of positioning behavior such as:

- anchoring at specific points on the fixed to element
- modifying the spacing between the fixed to and fixed element
- listening to resize events
- listening to scroll events and determining if the fixed to and fixed element
  are no longer in the viewport
- merging transition callbacks, styles, refs, etc
- setting the width for the fixed element to be equal to the fixed to element
  or at least the min width of the fixed to element
- prevent overlapping the fixed to element
- prevent swapping to the other side to fit within the viewport
- prevent fixing within the viewport
- adding a `transform-origin` based on the position anchor
- setting an `initialX` and `initialY` value to appear from a specific point
- dynamically generating the position options
- and more!

There is a lot of behavior, so this next example is just a playground showcasing
and commenting most of the features allowing you to see how they affect the fixed
element.

```demo source="./AdvancedConfiguration.tsx"

```

### Parameters

- `options` - An object with the following definition:

```ts disableTransform
export interface FixedPositioningOptions<
  FixedToElement extends HTMLElement,
  FixedElement extends HTMLElement,
>
  extends
    FixedPositioningTransitionOptions<FixedElement>,
    CalculateFixedPositionOptions {
  /**
   * An optional style that will be merged with the fixed positioning required
   * styles.
   *
   * @see {@link FixedPositionStyle}
   */
  style?: CSSProperties;

  /**
   * A ref pointing to an element that another element should be fixed to. This
   * **must** be provided for the positioning to work.
   */
  fixedTo: RefObject<FixedToElement>;

  /**
   * An optional function that can be used to override positioning options if
   * some options require the element to be in the DOM for specific
   * calculations.
   */
  getFixedPositionOptions?: () => CalculateFixedPositionOptions;

  /**
   * An optional function to call if the page resizes while the `FixedElement`
   * is visible.
   */
  onResize?: EventListener;
  /** @see {@link TransitionScrollCallback} */
  onScroll?: TransitionScrollCallback<FixedToElement, FixedElement>;

  /**
   * Set this to `true` to disable the fixed positioning behavior so it can be
   * customized within CSS or manually instead. This was added mostly to just
   * support rendering menus inline with other content (like autocompletes
   * within a dialog).
   *
   * @defaultValue `false`
   * @since 6.0.0
   */
  disabled?: boolean;
}

export interface FixedPositioningTransitionOptions<
  E extends HTMLElement,
> extends FixedPositioningTransitionCallbacks {
  /** {@inheritDoc TransitionOptions.nodeRef} */
  nodeRef?: Ref<E>;
}

export type FixedPositioningTransitionCallbacks = Pick<
  TransitionCallbacks,
  "onEnter" | "onEntering" | "onEntered" | "onExited"
>;

export interface InitialCoords {
  /**
   * The initial x value to use when calculating the position instead of
   * finding the container element to determine the the correct position. All
   * the other positioning logic will still be in effect to ensure the element
   * will be visible within the viewport.
   */
  initialX?: number;

  /**
   * The initial y value to use when calculating the position instead of
   * finding the container element to determine the the correct position. All
   * the other positioning logic will still be in effect to ensure the element
   * will be visible within the viewport.
   */
  initialY?: number;
}

/** @since 4.0.0 */
export interface CalculateFixedPositionOptions extends InitialCoords {
  /**
   * The configuration to anchor the fixed element to the container element.
   *
   * @defaultValue `BELOW_CENTER_ANCHOR`
   */
  anchor?: PositionAnchor;

  /**
   * The viewwidth margin to apply so that the element doesn't need to be
   * directly on the screen edge.
   *
   * @defaultValue `16`
   */
  vwMargin?: number;

  /**
   * The viewwidth margin to apply so that the element doesn't need to be
   * directly on the screen edge.
   *
   * @defaultValue `16`
   */
  vhMargin?: number;

  /**
   * The container width margin to apply so that the element doesn't need to be
   * directly on the container's edge.
   *
   * @defaultValue `0`
   */
  xMargin?: number;

  /**
   * The container height margin to apply so that the element doesn't need to be
   * directly on the container's edge
   *
   * @defaultValue `0`
   */
  yMargin?: number;

  /** {@inheritDoc PositionWidth} */
  width?: PositionWidth;

  /**
   * Boolean if the style object should include the `transformOrigin` value
   * based on the x and y positions.
   *
   * @defaultValue `false`
   */
  transformOrigin?: boolean;

  /**
   * Boolean if the fixed element should no longer be able to overlap the
   * container element. This is useful for autocomplete menus or other
   * components that retain focus on the container element while the fixed
   * element becomes visible.
   *
   * @defaultValue `false`
   */
  preventOverlap?: boolean;

  /**
   * Boolean if the auto-swapping behavior should be disabled. It's normally
   * recommended to not disable this since it'll allow elements to appear off
   * screen.
   *
   * @defaultValue `false`
   * @since 5.0.0 This will always be `true` if the
   * {@link FixedPositionOptions.container} is `null`.
   * @since 5.1.6 Allow this to be `false` while the `container` is
   * null. I can't figure out why I prevented that.
   */
  disableSwapping?: boolean;

  /**
   * Boolean if the fixed positioning should no longer prevent the fixed element
   * to be positioned within the viewport. This is nice if you want to allow for
   * full page scrolling instead and manually set a max-height on your element.
   *
   * @defaultValue `false`
   */
  disableVHBounds?: boolean;
}
```

### Returns

```ts disableTransform
export interface FixedPositioningImplementation<E extends HTMLElement> {
  /**
   * A ref that should be passed to a component for the fixed positioning
   * behavior to work correctly.
   *
   * This should really only be used if the {@link TransitionOptions} is not
   * being used.
   */
  ref: RefCallback<E>;

  /**
   * This is the {@link FixedPositionStyle} merged with the
   * {@link FixedPositioningOptions.style}. This will only return `undefined`
   * when {@link FixedPositioningOptions.disabled} is `true` and no `style` was
   * provided.
   */
  style: CSSProperties | undefined;

  /**
   * This should really only be used if the {@link transitionOptions} is not
   * being used.
   */
  callbacks: Readonly<Required<FixedPositioningTransitionCallbacks>>;

  /**
   * A function that can be called to update the style for the fixed element.
   */
  updateStyle: () => void;

  /** {@inheritDoc FixedPositioningTransitionOptions} */
  transitionOptions: Readonly<Required<FixedPositioningTransitionOptions<E>>>;
}
```

### See Also

- [useCSSTransition](./use-css-transition)
- [useCSSTransition Example](/components/css-transition#simple-usecsstransition-example)
- [Fixed Dialog](/components/dialog#fixed-dialog)
- [Menu](/components/menu)
